Vite 插件
VitePress 是基于 Vite 进行搭建，因此可以编写 Vite 插件来辅助完成一些在无法在浏览器环境完成的动作，比如在 VitePress 启动后，扫描文档目录下的 Markdown 文件，提取 frontmatter 的信息进行分析，或在渲染 Markdown 内容前，对其进行加工。
得益于 Vite 环境，Teek 内置了一些 Vite 插件来执行在 Node 环境才能完成的事情，这些插件分别为：
- vitepress-plugin-permalink
- vitepress-plugin-sidebar-resolve
- vitepress-plugin-md-h1
- vitepress-plugin-catalogue
- vitepress-plugin-doc-analysis
- vitepress-plugin-file-content-loader
- vitepress-plugin-auto-frontmatter
这些插件已经上传至 NPM 仓库，具体的使用说明可以前往 NPM 查看使用说明，或者访问 Github 仓库，每个插件下都有 README.md 文档介绍。
也可以在 Teek 的 配置项 中查看这些插件。
vitepress-plugin-permalink
Teek 使用 vitepress-plugin-permalink 来实现永久链接功能。
如果想要禁用该插件，进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
permalink: false,
},
});Teek 默认扫描文档根目录下（.vitepress 层级开始）的所有 Markdown 文件，如果希望忽略某些目录，可进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
permalinkOption: {
ignoreList: ["目录名"], // 支持正则表达式
},
},
});当希望只扫描指定的目录，可进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
permalinkOption: {
path: "guide", // 基于 .vitepress 目录层级添加，开头不需要有 /
},
},
});国际化
vitepress-plugin-permalink 支持国际化功能，在生成 permalink 时，默认会给不同语言文档的 permalink 添加语言前缀。
假如存在一个 Markdown 文档 guide.md，frontmatter 内容如下：
---
title: guide
permalink: /guide
---国际化目录结构如下；
docs/
├─ es/
│ ├─ guide.md
├─ guide.md那么在生成 permalink 时，es 语言下的 guide.md 的 permalink 为 /es/guide。
配置项
permalinkOption 的详细配置项请看 Permalink 配置项。
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
permalinkOption: {
/** 配置项 */
},
},
});vitepress-plugin-sidebar-resolve
Teek 使用 vitepress-plugin-sidebar-resolve 来实现自动生成侧边栏功能。
在 结构化目录 - 特殊目录 和 结构化目录 - 文档风 中已经介绍了该插件部分使用方式以及注意事项，如果想要禁用该插件，进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
sidebar: false,
},
});国际化
在国际化的环境下，当把 root 语言（默认语言）的 Markdown 文件放到某个路径下时，vitepress-plugin-sidebar-resolve 无法感知到，因此请使用 localeRootDir 配置项告诉它，在 国际化特殊场景 有说明。
配置项
sidebarOption 的详细配置项请看 SideBar 配置项。
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
sidebarOption: {},
/** 配置项 */
},
});侧边栏初始化格式
配置项 initItems 和 initItemsText 会影响侧边栏的生成格式，举个例子说明：
假设根目录下有目录名为 guide：
- 当
initItems为 true，则最终结果为sidebar: { "/guide": { items: [], collapsed }}- 当
initItemsText为 true，则最终结果为sidebar: { "/guide": { text: "guide", items: [], collapsed }} - 当
initItemsText为 false，则最终结果为sidebar: { "/guide": { items: [] }}
- 当
- 当
initItems为 false，则最终结果为sidebar: { "/guide": [] }
侧边栏新增图标 v1.4.1
如果希望侧边栏标题前新增图标，可以在 frontmatter.title 配置：
---
title: <i class='iconfont icon-teek'></i> 我是标题
---或者单独使用 frontmatter.sidebarPrefix 或 frontmatter.sidebarSuffix 配置， 插件会将图标并添加到标题前/后
---
sidebarPrefix: <i class='iconfont icon-teek'></i>
sidebarSuffix: <i class='iconfont icon-teek'></i>
---如果使用的是 iconfont 图标，每次使用都要加 <i class='iconfont icon-{xxx}'></i> 比较麻烦，因此插件提供了 prefixTransform 和 suffixTransform 配置项，可以对所有的 sidebarPrefix 和 sidebarSuffix 进行二次处理，如：
import { defineConfig } from "vitepress";
import Sidebar from "vitepress-plugin-sidebar-resolve";
export default defineConfig({
vite: {
plugins: [
Sidebar({
prefixTransform: prefix => {
// 判断是否为 HTML 标签，如果是则直接返回
const htmlTagRegex = /^<([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/;
if (htmlTagRegex.test(prefix)) return prefix;
return `<i class="iconfont icon-${prefix}"></i>`;
},
}),
],
},
});此时在 frontmatter.sidebarPrefix 配置如下即可生效：
---
sidebarPrefix: teek
---上面演示的是如何在标题前缀添加图标，后缀操作同理。
vitepress-plugin-md-h1
Teek 使用 vitepress-plugin-md-h1 来给文章页生成一级标题（假如 Markdown 文档没有设置过一级标题）。
一级标题获取顺序：frontmatter.title > 文件名
提示
只在页面加载 Markdown 内容时生成一级标题，并不会真正修改 Markdown 文档内容。
假设一个文档 install.md 的 frontmatter 内容如下：
---
title: guide
---在页面访问该文档时，页面自动生成一级标题 guide，当把 frontmatter.title 去掉后，页面的一级标题变为 install。
如果想要禁用该插件，进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
mdH1: false,
},
});配置项
mdH1Option 的详细配置项请看 MdH1Option 配置项。
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
mdH1Option: {
/** 配置项 */
},
},
});vitepress-plugin-catalogue
vitepress-plugin-catalogue 插件会将所有 frontmatter.catalogue 为 true 的文档信息挂载到 themeConfig.catalogues 中，Teek 使用该数据来生成目录页。
该插件与 Teek 强绑定，无法像上面的组件一样，通过 vitePlugins.catalogue = false 来禁用。
如果想要禁用该插件，只能通过禁用 Teek 主题来实现，配置如下：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
teekTheme: false, // 禁用 Teek 主题
});如果某个 markdown 文档不想被纳入目录里，则：
---
inCatalogue: false
---配置项
catalogueOption 的详细配置项请看 Catalogue 配置项。
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
catalogueOption: {
/** 配置项 */
},
},
});vitepress-plugin-doc-analysis
Teek 使用 vitepress-plugin-doc-analysis 来实现站点信息和文章页信息功能。
vitepress-plugin-doc-analysis 在 VitePress 启动后，扫描所有的 Markdown 文档，然后统计文章数量，文章字数等，最终将分析后的数据挂载到 themeConfig.docAnalysisInfo 中。
在首页看到的站点信息、文章页看到的文章字数、预计阅读时间等，都是使用 themeConfig.docAnalysisInfo 的数据来构成。
如果不希望某个 Markdown 文档被插件分析，请在该文档 frontmatter 配置：
---
docAnalysis: false
---如果想要禁用该插件，进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
docAnalysis: false,
},
});关于文章的预计阅读时间的计算，该插件默认 1 分钟内阅读的中文字数为 300，1 分钟内阅读的英文字数为 160，如果认为不合理，可以对其进行修改：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
docAnalysisOption: {
cn: 400,
en: 200,
},
},
});国际化
当处于国际化环境下，插件将不同语言的数据挂载到 locales.[lang].themeConfig.docAnalysisInfo。
配置项
docAnalysisOption 的详细配置项请看 DocAnalysis 配置项。
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
docAnalysisOption: {
/** 配置项 */
},
},
});vitepress-plugin-file-content-loader
Teek 使用 vitepress-plugin-file-content-loader 来构建首页的文章列表和归档页数据，并挂载到 themeConfig.posts 中。
该插件本质上将 VitePress 官网的 构建时数据加载 功能转为插件，因此具体的介绍说明请前往 VitePress 官网阅读。
为什么设计为插件？
构建时数据加载功能是在访问网站的时候开始执行，如果使用该功能扫描了大量的 Markdown 文档，那么会导致第一次进入页面卡顿，因此基于该功能实现了插件，在项目启动过程完成数据的加载。
该插件与 Teek 强绑定，如果想要禁用该插件，只能通过禁用 Teek 主题来实现，配置如下：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
teekTheme: false, // 禁用 Teek 主题
});国际化
当处于国际化环境下，插件将不同语言的数据挂载到 themeConfig.posts.locales.[lang] 下。
配置项
通过 fileContentLoaderIgnore 配置项告诉插件扫描 Markdown 文档时，指定忽略路径，格式为 glob 表达式，如 test/\*\*
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
fileContentLoaderIgnore: [],
},
});vitepress-plugin-auto-frontmatter
Teek 使用 vitepress-plugin-auto-frontmatter 自动给 Markdown 文档添加 frontmatter。
该插件会直接修改 Markdown 文档的 frontmatter，因此为了安全性考虑，默认是关闭的，如果希望开启，进行如下配置：
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
autoFrontmatter: true,
},
});如果开启了该插件，那么 Teek 将会对所有 Markdown 文档的 frontmatter 添加如下格式：
---
title: getting
date: 2025-03-03 00:45:16
permalink: /pages/eb8f2f
categories:
- guide
---title为文章的标题date为文章的创建时间permalink为文章的永久链接，采用随机数确保唯一categories为文章的分类，根据目录层级获取
提示
Teek 不会修改已经存在的数据，判断的规则是比较 key，不比较 value。
如果需要拓展自定义 frontmatter，让 Teek 在生成 frontmatter 的时候额外添加其他数据，请使用 transform 配置项，具体使用请看 vitepress-plugin-auto-frontmatter 的 Example 2 和 Example 3。
配置项
autoFrontmatterOption 的详细配置项请看 AutoFrontmatter 配置项。
Teek 在 vitepress-plugin-auto-frontmatter 的配置项基础上额外添加两个配置项：
- permalinkPrefix：自动生成
permalink的固定前缀，如pages、pages/demo，默认为pages - categories：是否自动生成
categories
import { defineTeekConfig } from "vitepress-theme-teek/config";
const teekConfig = defineTeekConfig({
vitePlugins: {
autoFrontmatter: true,
autoFrontmatterOption: {
permalinkPrefix: "pages", // 自动生成 permalink 的固定前缀，如 pages、pages/demo，默认为 pages
categories: true, // 是否自动生成 categories
// ...
},
},
});